<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>TraceParserGen Users Guide</title>
    <style>
        body {
            font-family: Segoe UI,SegoeUI,Segoe WP,Helvetica Neue,Helvetica,Tahoma,Arial,sans-serif;
            font-weight: 400;
            text-rendering: optimizeLegibility;
            -webkit-font-smoothing: antialiased;
        }

        hr {
            border-top: 3px double gray;
        }
    </style>
</head>
<body>
    <h2> TraceParserGen Users' Guide </h2>
    <p>
        TraceParserGen is tool for taking ETW manifest files (as generated from tracerpt
        -export), and generating C# subclasses of TraceEvent which can parse the events
        into strongly type managed objects.&nbsp;
    </p>
    <p>
        You can generate a ETW manifest file from an ETL file by using the -export
        option on the &#39;traceRpt&#39; command
    </p>
    <ul>
        <li>tracerpt -export manifestFile.man inputFile.etl </li>
    </ul>
    <p>
        Once you have the manifest, you generate C#&nbsp; subclasses of TraceEvent which
        understand those events by doing
    </p>
    <ul>
        <li>&nbsp;traceParserGen&nbsp; manifestFile.man manifest.cs</li>
    </ul>
    <p>
        You can then add &#39;manifest.cs&#39; to your project, and link it against the
        TraceEvent.dll to form a complete parser for your new events.&nbsp;
    </p>
    <p>
        The default outputfile is derived by simply changing the file extension to .cs
        thus the command above can be abbreviated to
    </p>
    <ul>
        <li>&nbsp;traceParserGen&nbsp; manifestFile.man </li>
    </ul>
    <h3>
        Merge Support
    </h3>
    <p>
        It is likely that you will want to update the .CS file that was generated from
        TraceParserGen.&nbsp; Possibly to give better names to operations, add missing
        information (like enumating type), or to simply fix errors from the original
        manifest.&nbsp; This presents a problem if you want to regenerated the .CS file
        from the manifest again (either because TraceParserGen was updated to produce
        &#39;better&#39; templates, or more events were added to the manifest.&nbsp;
    </p>
    <p>
        This problem can be solve by Saving the original file generated by
        TraceParserGen before making any local modifications (suggested name is <i>
            filename
        </i>.base.cs).&nbsp; This allows a 3 way difference to be done between
        the newly generated .CS file, the original generated .CS file and the
        user-modified CS file.&nbsp;
    </p>
    <p>
        The /merge option of TraceParserGen supports this mode.&nbsp; If you typed
    </p>
    <ul>
        <li>
            TraceParserGen /merge<i> providerMetaData.</i>man<i> providerMetaData</i>.cs
            /basline <i>providerMetaData</i>.base.cs
        </li>
    </ul>
    <p>
        TraceParTraceParserGen will then
    </p>
    <ol>
        <li>
            Rename <i>providerMetaData</i>.cs to
            <i>providerMetaData.<b>NUM</b>.cs </i>and<i> and providerMetaData.base.cs </i>to<i> providerMetaData</i>.<i><b>NUM</b></i>.base.cs
            where <b>NUM</b> is the first decimal number that ensures that the
            new files don&#39;t clobber existing ones.&nbsp;&nbsp;
        </li>
        <li>Create a new manifest generated C# into <i>providerMetaData</i>.base.cs </li>
        <li>
            Do a 3 way merge between the newly generated <i>providerMetaData</i>.base.cs and
            <i>providerMetaData.<b>NUM</b>.cs (</i>the original user-modified file), using
            <i>providerMetaData</i>.<i><b>NUM</b></i>.base.cs as the base.&nbsp;
        </li>
    </ol>
    <p>
        The result is that user-modifications will be merged into the newly generated
        data.&nbsp;&nbsp;&nbsp; Ultimately the numbered files can be deleted, but are
        handy in case something goes wrong.&nbsp;
    </p>
    <p>
        The default for the baseline is to change the extension to .base.cs, so the
        command above can be abbreviated to
    </p>
    <ul>
        <li>TraceParserGen /merge<i> providerMetaData.</i>man</li>
    </ul>
</body>
</html>
